Should these be public or private ?

I think these should be private and final to easily ensure the @ThreadSafe is respected.

Agree, updated from public to private final.

1- Consider renaming this to something like, TTL_ATTRIBUTE_METADATA_KEY, current name is too vague
2- This Key is under @SdkPublicApi class, because the class is @SdkPublicApi, everything public on it becomes part of the public API contract, but it is only used from UpdateTimeToLiveOperation which is an SdkInternalAPI for any backward compatibility issues going forward. Consider either making the field package-private (so UpdateTimeToLiveOperation in the same package can still access it), or moving the constant to an @SdkInternalApi shared utility class...

1. Agree, but this is the pattern used for the other extensions.
2. I would go with the last approach, and create an @SdkInternalApi shared utility class - and place there all *_ATTRIBUTE_METADATA_KEY for extensions. Would make sense? wouldn't make too much sense to create the class only for TimeToLive extension attributes... what do you think?

BeanTableSchema validates that only one TTL attribute exists, but StaticTableSchema has no such guard. Since modifyMetadata stores a Map (not a Collection) via addCustomMetadataObject, a second TTL attribute silently replaces the first with no error:

StaticTableSchema.builder(MyItem.class)
    .addAttribute(Long.class, a -> a.name("ttl1")
        .getter(MyItem::getTTL1).setter(MyItem::setTTL1)
        .tags(timeToLiveAttribute("createdAt", 30, ...)))
    .addAttribute(Long.class, a -> a.name("ttl2")
        .getter(MyItem::getTTL2).setter(MyItem::setTTL2)
        .tags(timeToLiveAttribute("updatedAt", 7, ...)))
    .build();
// ttl1 config is silently lost, only ttl2 is tracked

DynamoDB only supports one TTL attribute per table, so this is always a user error, but the SDK should fail loudly rather than silently dropping one.

Recommendation: You may consider moving the validation into TimeToLiveAttribute.modifyMetadata() so it works for all schema types

Agree, the validation is applied only on BeanTableSchema and I am preparing parameterized tests to cover the remaining schemas with validation updated - tests still in progress, have pretty many scenarios to cover with different record types.

Also, I feel like addCustomMetadataObject is not consistent in terms of validation:

       private void mergeCustomMetaDataObject(String key, Object object) {
            if (object instanceof Collection) {
                this.addCustomMetadataObject(key, (Collection<Object>) object);
            } else if (object instanceof Map) {
                this.addCustomMetadataObject(key, (Map<Object, Object>) object);
            } else {
                this.addCustomMetadataObject(key, object);
            }
        }

because the else branch throws an exception when finds duplicates:

        public Builder addCustomMetadataObject(String key, Object object) {
            if (customMetadata.containsKey(key)) {
                throw new IllegalArgumentException("Attempt to set a custom metadata object that has already been set. "
                                                   + "Custom metadata object key: " + key);
            }

            customMetadata.put(key, object);
            return this;
        }

This means every existing DynamoDbEnhancedClient using default extensions will now run TimeToLiveExtension.beforeWrite() on every write operation, even for tables
with no TTL attributes. The extension does an early return when no metadata is found, but we still change the behavior:

1. Performance: An additional extension in the chain for every write across the entire SDK, for all users, even those who never use TTL. The customMetadataObject() lookup + Optional.orElse(null) runs on every putItem/updateItem/batchWriteItem/transactWriteItems.

2. Double registration: Users who extend the defaults will register TTL twice:

   // This is how TimeToLiveRecordTest in this PR does it — TTL extension runs twice per write
   DynamoDbEnhancedClient.builder()
       .extensions(Stream.concat(
           ExtensionResolver.defaultExtensions().stream(),
           Stream.of(timeToLiveExtension))
           .collect(Collectors.toList()))
       .build();

Should we think about making this extension opt-in instead ?

also, if we want to keep this, The Javadoc comment on defaultExtensions() says "Currently this is just the VersionedRecordExtension", we may need to update it

consider adding javadoc, also applies to UpdateTimeToLiveEnhancedResponse and to Async table

javadoc added

Do we want to support local time ?

if (baseValue instanceof LocalTime) {
    return LocalDate.now().atTime((LocalTime) baseValue).plus(duration, unit).toEpochSecond(ZoneOffset.UTC);
}

two potential problems:

1. Midnight jump: LocalDate.now() defines what "today" means, and that changes at midnight. Items with the same LocalTime base value and duration get TTLs that differ by a day depending on which side of midnight the write lands:

• Write at 11:59 PM March 10 -> LocalDate.now() = March 10-> TTL = March 11 00:05 (expires in ~6 minutes)
• Write at 12:01 AM March 11 -> LocalDate.now() = March 11-> TTL = March 12 00:05 (expires in ~24 hours)

2. JVM timezone dependency: LocalDate.now() uses ZoneId.systemDefault(), but the epoch conversion uses ZoneOffset.UTC. If the JVM runs in America/New_York, LocalDate.now() could return a different date than UTC, shifting the TTL by hours depending on where the server runs.

If you say, LocalDate.now(ZoneOffset.UTC), it would fix problem 2, but problem 1 is still there to LocalTime having no date component, there's always a midnight boundary where the TTL jumps by 24 hours.

Recommendation: You may consider removiong LocalTime support and let it fall through to the existing IllegalArgumentException if that's acceptable. The other five types (Instant, LocalDate, LocalDateTime,
ZonedDateTime, Long) are all deterministic and cover every real TTL use case. Users who need time-of-day-based TTL can compute the epoch seconds themselves with explicit control over the date and timezone.

I strongly suggest we only use UTC and only support Instant with a Clock parameter like in AutoGeneratedTimestampRecordExtension.

If any key is missing or has a wrong type (like someone manually constructs metadata via StaticTableMetadata.builder().addCustomMetadataObject(...)), these lines will throw NullPointerException with no context about which key failed or why. Can consider to use Validate.notNull() with descriptive messages..

I agree and a wrong type would throw a different exception and require a dedicated check.

Added validation.

Is this supposed to be private ?

table() function name is misleading, may consider renaming it to something like timeToLiveSpecification() ?

Updated, should be fine now.

I guess not DescribeTimeToLive , probably mistake ?

Yes, updated.

Is this and RecordWithSimpleTTL dead code?

I think we should cover this in the unit tests.

Should we check this is not negative somewhere?

Added validation for duration in modifyMetadata and beforeWrite, I will have a look if there is a better place for this validation.

Why are we not using validateMetadataValue helper method ?

I think this Message is Confusing a bit, it exposing Internal Logic, instead of helping caller to help fix the issue.

It should be more readable to caller having something like No TTL attribute is configured in the table schema for table, Use @DynamoDbTimeToLiveAttribute on a Long getter....

Classes / Interfaces should have @ since tags

I think we should add baseFieldName check as well, here.
What happens if User does @DynamoDbTimeToLiveAttribute(duration=30, unit=DAYS) — forgot baseField.

It would be silent no-op when duration > 0 and baseField="".